===== PAGE 1 =====
GEN3 ETHERNET MODULE
Web Interface Quick Start Guide
National Control Devices
===== PAGE 2 =====
G E N 3 E T H E R N E T
Chapter
1
Introduction
Gen3 Ethernet Module
In this guide we will cover the configuration and use of the NCD Gen 3
Module. We will discuss the configuration software as well as the web
interface. The module can be configured through the web interface,
however if you have a Windows Computer available, we recommend
configuring settings in the module through the configuration software.
Basic Usage
For most users, the Gen 3 Ethernet module will work right out of the box
with no settings configuration required. Simply install the Ethernet
module into your main control board, connect a standard ethernet cable to
the Gen 3 module, connect the other end of the ethernet cable into your
network, then power up the main control board. Your main control board
Power LED(s) should turn on and the LEDs on the front of the Ethernet
module should turn on and begin flashing which indicates the module is in
fact powered up normally.
At this point you can open the Base Station software or Alpha
Station software and communicate with the main control board through
the Gen 3 Module. Both Base Station and Alpha Station should
automatically discover the Gen 3 module on the network and allow you to
connect to the main control board.
1
===== PAGE 3 =====
G E N 3 E T H E R N E T
Chapter
2
Important Details
DHCP
By default, NCD Gen 3 modules ship in DHCP mode so it is expected that they
be connected to a DHCP enabled networks. Most routers support DHCP,
however if your network does not support DHCP then you will want to store
a static IP address into the controller.
Force Static IP for Configuration
If your network does not support DHCP then power down the main control
board. Install a jumper on the two pins directly to the left of the Ethernet
Jack then power the board up again. Installing a jumper on these two pins
will force the module to use a Static IP address of 192.168.1.88. This will
allow you to connect to the Gen 3 Module for configuration on a Non DHCP
enabled network or by connecting the Ethernet module directly to the
Ethernet port of your PC. When configuring settings in this way you will
need to leave the static IP address jumper in place, alter the settings, select
“Apply Settings”, power down the control board, wait 2 seconds, remove the
static IP jumper, and power the board back up for the settings to be stored in
the module.
Factory Reset
There is a hardware method of restoring the Gen 3 module to factory default
settings. To do this press and hold the button to the right of the Ethernet
Jack for 5 seconds, then release the button. This will factory reset all setting
inside the Gen 3 module.
Note
Always connect the Ethernet cable to the Gen 3 module and the network
prior to powering the board up.
Applying Settings
Any time settings are altered on the Gen 3 module it is necessary to power
cycle the module. This can be done by manually removing power from the
host board or by clicking the Reset button in the software/web interface.
2
===== PAGE 4 =====
G E N 3 E T H E R N E T
NCD Config Tool Software
If you need to make configuration changes to the Gen 3 module and you
have a windows computer available, we highly recommend using this NCD
Config Tool software to make your configuration changes:
NCD5500 Configuration Software for Windows
If you do not have a Windows computer available or cannot install this
software for another reason, please proceed to the Web Interface
Configuration section.
Discovering Gen 3 Modules with the NCD Config Tool
Download and install the NCD Config Tool from the link above on a
Windows computer connected to the same network as the Gen 3
module. Once installed open the NCD Config Tool software.
Power on the Main
Control board with the
Gen 3 module. After 20
seconds or so the
module should appear
in the list as a MAC
address, if it does not
click the Search button
until the module
appears in the list.
From here all settings
of the Gen 3 module
may be configured.
If the IP address shows up as 0.0.0.0 go ahead and click the Search button
again and the IP address should appear in the IP Address Field.
We will now cover all settings that may be configured through the NCD
Config Tool Software. You will notice two tabs on the software labeled
Basic Settings and Advanced Options. We will cover each of these
categories of settings individually.
Once settings are configured as desired click the Apply Settings button to
store them into the Gen 3 module. It is also possible to power cycle the
module with the Reset Button. Keep in mind settings entered in the
module do not take effect until the module is power cycled.
3
===== PAGE 5 =====
G E N 3 E T H E R N E T
Basic Settings
Network Settings(Use the Follow IP address)
When this radio button is selected it forces the Gen 3 module to utilize the
Static IP address settings entered by the user in the IP Address, Subnet
Mask, Gateway, and DNS Server fields.
Network Settings (Get IP address from DHCP Server)
When this radio
button is selected
the Gen 3 module
will obtain an IP
address from the
network router upon
boot. Configuration
settings entered in
the IP Address,
Subnet Mask,
Gateway, and DNS
Server fields will be
ignored however
these fields will still
display current
module information.
COM Port Settings
NCD Gen 3 Ethernet module ship with Com Port Settings which make the
module compatible with the Main Control board it is installed in. If any
settings are made to the COM Port Settings fields it must be assured that
these settings are compatible with the Main Control Board. For most
applications it is not recommended that these fields be changed.
Connection
These settings determine how Software will communicate with the Gen 3
module in daily use. Socket connection type may be selected from the
Work As drop-down menu. Options are TCP Server, TCP Client, or UDP. In
TCP Server mode the Gen 3 module will accept TCP socket connections
from your Software over the port specified in the Local Port Field. In TCP
Client mode the Gen 3 module will automatically establish a TCP socket to
a server on the IP specified in the Remote Host Field on the port specified
in the port field to the right of the Remote Host field. Lastly UDP mode
causes the Gen 3 Module to utilize UDP sockets. This is a good option if the
board needs to send information to multiple software applications running
on different servers.
4
===== PAGE 6 =====
G E N 3 E T H E R N E T
Advanced Options
Show Debug Messages
Not recommended for use in NCD Devices
Echo In AT Mode
Not recommended for use in NCD Devices
Use NetBIOS
Not recommended for use in NCD Devices
Device Name
Gen 3 module send out
discovery packets which
allow software to discover
them on the network. This
Device Name field allows
the user to specify the
name of this particular
device in the discovery
packet. This can be used
to differentiate between
devices if there are
multiple on the same
network.
Password
The Web interface of the Gen 3 module is password secured. Double click
the Password field here and it is possible to edit the web interface
password.
Enter Mode when power on or reset
Only Data mode is recommended for NCD Devices.
Enabled Web Server Port
By default the Gen 3 module serves its web interface on port 80 like most
normal web servers, however this field allows the user to alter the port the
web interface is served on. This field may be set to 0 if it is desired to
disable the web interface for the Gen 3 module.
Nagle Wait Time (ms):
This configures the amount of time the Gen 3 module waits after data is
initially received over its serial connection to the Main Control Board
before sending the data packet over the Network Socket. The
default/recommended setting for this field is 5.
5
===== PAGE 7 =====
G E N 3 E T H E R N E T
Data Length:
This is the amount of data required to be received over the Serial
connection to the Main control board before the data packet is sent out
over the Network Socket. For use in NCD Devices it is recommended to
leave this setting at 0.
Clear Data Buffer when TCP Connected
The Gen3 module has an internal buffer where data received over it’s serial
connection may be stored. This setting determines whether or not that
data buffer should be emptied when a TCP socket connection is established
to the board or from the board to the Server. For most applications it is
recommended to leave this setting checked.
Request Admin Password
This setting is only available when the Gen 3 module is in TCP Server
Mode. This setting requires software connecting to the Gen 3 module to
submit a password in order to communicate with it. The Password from
the Password field is utilized as the connection authorization password. It
should be noted that this setting has not yet been thoroughly tested by
NCD Staff.
Connect TCP Server When
This setting is only available when the Gen 3 module is in TCP Client
Mode. This setting determines when a socket should be established with
the Remote Host TCP server. Options are Power On and Serial Data
Received.
Auto Message
This setting determines whether the Gen 3 module should send a message
to the Client or Server when a socket is initially established. This is not
necessary for most applications as it is possible to retrieve this information
from the socket, however it may be utilized to identify the device to the
software. Options are No Message, Device Name, Device IP, or Device MAC
address.
Inactivity(ms)
This setting determines how long a socket will be maintained if no data is
transmitted or received over a network socket connection. After this
amount of time the Gen 3 module will disconnect the socket. If it is not
desired to automatically disconnect the socket after no data is transferred
for a specified amount of time set this field to 0.
6
===== PAGE 8 =====
G E N 3 E T H E R N E T
Reconnection(ms):
This setting is only applicable in TCP Client mode. This setting determines
the amount of time the Gen 3 module will wait after a connection has been
closed by the remote Host. After this amount of time the Gen 3 module will
attempt to reconnect to the remote Host.
Keep Alive (5s):
This is the interval in 5 second increments the Gen 3 module will send
keep alive packets to the remote host/client.
7
===== PAGE 9 =====
G E N 3 E T H E R N E T
Setting Web Interface
The NCD5500 allows you to easily change from a simple TCP socket or UDP
datagram communication architecture over to a web interface based
control and monitoring system. This interface is usable out of the box or
completely customizable using HTML, CSS, and JS.
Compatibility
Currently the Web Interface configuration of the NCD5500 Ethernet
module is only compatible with ProXR Lite.
Software Setup
Follow these steps to set up the software. The diagram below the steps will
correspond to a step number.
1. Navigate to the NCD5500 Repository at https://github.com/ncd-
io/NCD5500-Files
2. On the repository page, download the repository (Code Button>
Download ZIP)
3. Unzip the file you just downloaded
4. Run the NCD5500 Configuration utility (/configuration/NCD
ConfigTool.exe)
5. Make sure that the IP address drop down in the top left has the IP
address of your computer on the network (Figure 1)
o Some windows computers have a loopback interface that
will display here. This interface will have an IP address such
as 127.0.0.1. Do not choose this interface
6. Click the “Search” Button (Figure 1)
7. Select the MAC address of the device you would like to configure
(Figure 1)
o You can match the MAC address displayed here against the
one printed on the top of the ethernet module
o If the device shows an IP address of 0.0.0.0 it has not fully
booted yet, select search again until a valid IP address is
displayed
8. Under the “Connections” section change “Work As” to “3. Web-i”
(Figure 1)
9. Click on the “Upload” button along the top of the NCD5500
Configuration Utility (Figure 1)
10. Select Upload Firmware
11. In the file explorer that comes up navigate to the unzipped
firmware folder and upload the file marked NCD5500.bin
8
===== PAGE 10 =====
G E N 3 E T H E R N E T
12. Allow this upload time to process
13. Once the firmware has finished uploading click on the Reset button
along the top of the application and click on “Reset Now!”
14. Click on the “Upload” button along the top of the NCD5500
Configuration Utility again and select “Upload Webpage”
15. In the file explorer that pops up navigate to the unzipped firmware
folder and go to the HTML folder inside of it
16. Choose the .html file appropriate for the number of relays you have
on your relay controller
9
===== PAGE 11 =====
G E N 3 E T H E R N E T
Confirmation
1. The NCD5500 Utility will display the IP address of the module in the
“Network Settings” section next to the label “IP Address” (Figure 2)
2. Enter the IP address displayed here into the URL bar of your
computer’s browser (we recommend google chrome)
3. Log in the with default password of “admin” without the quotes
4. In the left navigation select “Web-i” (Figure 3)
5. You should now see controls for each relay on your controller with
its current status.
6. Click on the “Toggle” button to make sure that the status of the relay
updates (Figure 3)
10
===== PAGE 12 =====
G E N 3 E T H E R N E T
Customization
Number, Names, and Buttons for Relays
The NCD5500 module does not have on-board storage for variables so you
must alter the HTML files saved into the module. First you will need to
have the .HTML file for your board which can be obtained
from: https://github.com/ncd-io/NCD5500-Files.
1. Open the HTML file for your relay controller with a text or code
editor. I recommend Atom (atom.io) or Notepad++ (notepad-plus-
plus.org/downloads/)
2. Perform a find operation (CTRL+F) and look for
“get_standard_ui_json” without the quotes
o This function simply builds and returns an object in JSON
format to the UI constructor
o You can alter the number of relays using the
number_of_relays property
o You can alter the names of the relays using the names
property. If you do no name all of the relays your UI is
configured to show then the unnamed relays will be labeled
Relay X where X is the relay number
o You can add and remove control buttons using the buttons
property. By default On, Off, and Toggle are shown. The
property name here is the function that will be called when
the button is clicked. The property value is the text displayed
on the button. By default these buttons will also call
query_relay_bank_status and update_relay_bank_status_ui in
order to update the UI with the new state of the relay.
3. Alter this function to suit your requirements
4. Save this file
5. Use the NCD5500 Configuration Utility to find and upload the new
.html file
11
===== PAGE 13 =====
G E N 3 E T H E R N E T
Macros
The NCD5500 module does not have on-board storage for variables so you
must alter the HTML files saved into the module. First you will need to
have the .HTML file for your board which can be obtained
from: https://github.com/ncd-io/NCD5500-Files.
1. Open the HTML file for your relay controller with a text or code
editor. I recommend Atom (atom.io) or Notepad++ (notepad-plus-
plus.org/downloads/)
2. Perform a find operation (CTRL+F) and look for
“get_macros_ui_json” without the quotes
o This function simply builds and returns an object in JSON
format to the UI constructor
o You can alter the number of macros by creating a new object
keyed by integer index
o You can alter the label of the button by altering the label
property of each button object
o You can alter what is triggered after the macros are executed
for further parsing by altering the callbacks property. The
default callback simply displays the response on the Macros
page. Multiple callbacks can be entered and they will trigger
in the order entered
o You can alter what commands are executed by either
entering an integer array in for the command you wish to
send or calling a get_…_command function such as
get_toggle_relay_command to obtain the desired command
3. Alter this function to suit your requirements
4. Save this file
5. Use the NCD5500 Configuration Utility to find and upload the new
.html file
12
===== PAGE 14 =====
G E N 3 E T H E R N E T
Code
You can alter and customize the code of the web page itself if you want to.
NCD has limited support for doing so and a working knowledge of HTML5
is recommended.
KW AR GS
Many functions in the base code expect an argument called kwargs. This is
short for keyword arguments and allows you to pass context and variables
through our functions and access them through your own callbacks later
on down the communications flow. You can find an example of doing this
in our standard relay control code which passes the kwargs of ‘callbacks’
(array of function to pass GET request responses to) and ‘bank’ (specifies
the target bank for UI updates after getting current relay status’). This
argument is not required and will default itself to being empty if no kwargs
are passed. We recommend if you design your own code for the NCD5500
web interface to implement this practice as well.
C O M M AND F U NC T IO N L IS T
The list of callable commands is in development. Contact us for questions
or peruse the code. All of the pertinent functions will be listed after the
NCD_AJAX function.
software. Options are No Message, Device Name, Device IP, or Device MAC
address.
13
===== PAGE 15 =====
G E N 3 E T H E R N E T
Management
Password Setting
The Web interface is
password protected. The
default password for the
web interface is admin. If
desired, you may change
this password using the
Password Setting
Fields. After the new
password is set it will
take effect after the next
power cycle.
Factory Default
It is possible reset the
Gen 3 module to factory
default settings by
pressing this Default
Button
Reset Device
It is possible to power cycle the Gen 3 Module by pressing this Reset
Button.
Logout
This button will log the user out of the web interface. Keep in mind
password changes will not take effect until a power cycle to the module.
14
===== PAGE 16 =====
G E N 3 E T H E R N E T
Base Station Software
Base Station Software is our reference tool for designing and testing all
currently manufactured NCD Devices. Base Station will assist you in
learning how any NCD device functions and will provide valuable
diagnostic tools to help determine if your controller is functioning as
designed. Base Station software exercises every supported feature of every
supported device. It is the ultimate reference tool for learning, diagnosing,
and testing NCD devices.
Discovered Network Devices
Base Station will
discover the Ethernet
board on the network
and show you the IP
address assigned to the
board. Select
Discovered Network
Devices button then
click on the IP Address,
this will open your
browser and show you
the Web Interface
Connection and all its
features. By selecting
the Discovered
Network Devices button then clicking OK, Base Station Software will open
showing you the command sets that are available for your board.
Device Command Sets
Base Station software
asks the controller
which command sets
are supported. The
supported command
sets are listed when you
run the Base Station
software
application. Some
controllers may show
more command sets
while other controllers
may show fewer command sets. The Base Station program will decide
which command sets apply to your board.
15
===== PAGE 17 =====
G E N 3 E T H E R N E T
Troubleshooting
If you lose communications with the module follow these steps:
Factory Reset
1. Check that the Ethernet Module is seated correctly on the
connection socket of the board it is mounted on
2. Power up the module by applying power to the board the module is
mounted on
3. Press and hold the factory reset button on the side of the Ethernet
module for 5 seconds to reset the module back to factory settings
4. Use the NCD5500 Configuration Software for Windows to discover
the device
o Make sure that the IP address dropdown box in the top left
of the NCD5500 Configuration software is set to your
computer’s external IP address. If you select the dropdown
and only one IP address is listed, then you do not need to
change this
o If the correct network is selected in the top left dropdown
and the device is still not being discovered, try the steps in
the “Static IP Configuration” section below
5. Use the NCD5500 Software to configure your device to the desired
settings
6. Select Apply Settings at the top
7. Select Reset at the top
16
===== PAGE 18 =====
G E N 3 E T H E R N E T
Static IP Configuration
If the Factory Reset above does not discover the device
1. Check that the Ethernet Module is seated correctly on the
connection socket of the board it is mounted on
2. Use a jumper to connect the two pins on the Ethernet Module to
force the static IP address of 192.168.1.88 onto the module
3. Power up the module by applying power to the board the module is
mounted on
4. Connect the Ethernet Module directly to the Ethernet Port of your
computer
5. Use the NCD5500 Configuration Software for Windows to discover
the device
o Make sure that the IP address dropdown box in the top left
of the NCD5500 Configuration software is set to your
computer’s external IP address. If you select the dropdown
and only one IP address is listed then you do not need to
change this
o If the device is not discoverable at this point contact NCD’s
support team for additional steps
6. Use the NCD5500 Software to configure your device
7. Select Apply Settings at the top
8. Power down the ethernet module by removing power from the
board that the Ethernet Module is mounted on
9. Wait 2 seconds
10. Remove the Static IP jumper from the Ethernet Module
11. Power up the board
17
===== PAGE 19 =====
G E N 3 E T H E R N E T
Technical Support
Base Station Software is
NCD Community
National Control Devices has a forum where you can search and post
questions on the operation of the boards. The NCD Community is where
you will get the fastest support for all NCD products right from the
developers! Discussions are welcome on applications, and you are
encouraged to share your experiences with other users. Visit the
community here: community.ncd.io/
18
